Crate const_panic

source
Expand description

For panicking with formatting in const contexts.

This library exists because the panic macro was stabilized for use in const contexts in Rust 1.57.0, without formatting support.

All of the types that implement the PanicFmt trait can be formatted in panics.

§Examples

§Basic

ⓘ
use const_panic::concat_assert;

const FOO: u32 = 10;
const BAR: u32 = 0;
const _: () = assert_non_zero(FOO, BAR);

#[track_caller]
const fn assert_non_zero(foo: u32, bar: u32) {
    concat_assert!{
        foo != 0 && bar != 0,
        "\nneither foo nor bar can be zero!\nfoo: ", foo, "\nbar: ", bar
    }
}

The above code fails to compile with this error:

error[E0080]: evaluation of constant value failed
 --> src/lib.rs:20:15
  |
8 | const _: () = assert_non_zero(FOO, BAR);
  |               ^^^^^^^^^^^^^^^^^^^^^^^^^ the evaluated program panicked at '
neither foo nor bar can be zero!
foo: 10
bar: 0', src/lib.rs:8:15

When called at runtime

ⓘ
use const_panic::concat_assert;

assert_non_zero(10, 0);

#[track_caller]
const fn assert_non_zero(foo: u32, bar: u32) {
    concat_assert!{
        foo != 0 && bar != 0,
        "\nneither foo nor bar can be zero!\nfoo: ", foo, "\nbar: ", bar
    }
}

it prints this:

thread 'main' panicked at '
neither foo nor bar can be zero!
foo: 10
bar: 0', src/lib.rs:6:1
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

§Custom types

Panic formatting for custom types can be done in these ways (in increasing order of verbosity):

  • Using the PanicFmt derive macro (requires the opt-in "derive" feature)
  • Using the impl_panicfmt macro (requires the default-enabled "non_basic" feature)
  • Using the flatten_panicvals macro (requires the default-enabled "non_basic" feature)
  • Manually implementing the PanicFmt trait as described in its docs.

This example uses the PanicFmt derive approach.

ⓘ
use const_panic::{PanicFmt, concat_panic};

const LAST: u8 = {
    Foo{
        x: &[],
        y: Bar(false, true),
        z: Qux::Left(23),
    }.pop().1
};

impl Foo<'_> {
    /// Pops the last element
    ///
    /// # Panics
    ///
    /// Panics if `self.x` is empty
    #[track_caller]
    const fn pop(mut self) -> (Self, u8) {
        if let [rem @ .., last] = self.x {
            self.x = rem;
            (self, *last)
        } else {
            concat_panic!(
                "\nexpected a non-empty Foo, found: \n",
                // uses alternative Debug formatting for `self`,
                // otherwise this would use regular Debug formatting.
                alt_debug: self
            )
        }
    }
}

#[derive(PanicFmt)]
struct Foo<'a> {
    x: &'a [u8],
    y: Bar,
    z: Qux,
}

#[derive(PanicFmt)]
struct Bar(bool, bool);

#[derive(PanicFmt)]
enum Qux {
    Up,
    Down { x: u32, y: u32 },
    Left(u64),
}

The above code fails to compile with this error:

error[E0080]: evaluation of constant value failed
  --> src/lib.rs:57:5
   |
7  | /     Foo{
8  | |         x: &[],
9  | |         y: Bar(false, true),
10 | |         z: Qux::Left(23),
11 | |     }.pop().1
   | |___________^ the evaluated program panicked at '
expected a non-empty Foo, found:
Foo {
    x: [],
    y: Bar(
        false,
        true,
    ),
    z: Left(
        23,
    ),
}', src/lib.rs:11:7

§Limitations

Arguments to the formatting/panicking macros must have a fully inferred concrete type, because const_panic macros use duck typing to call methods on those arguments.

One effect of that limitation is that you will have to pass suffixed integer literals (eg: 100u8) when those integers aren’t inferred to be a concrete type.

§Panic message length

The panic message can only be up to MAX_PANIC_MSG_LEN long, after which it is truncated.

§Cargo features

  • "non_basic"(enabled by default): Enables support for formatting structs, enums, and arrays.
    Without this feature, you can effectively only format primitive types (custom types can manually implement formatting with more difficulty).

  • "rust_1_64"(disabled by default): Enables formatting of additional items that require Rust 1.64.0 to do so.

  • "derive"(disabled by default): Enables the PanicFmt derive macro.

§Plans

None for now

§No-std support

const_panic is #![no_std], it can be used anywhere Rust can be used.

§Minimum Supported Rust Version

This requires Rust 1.57.0, because it uses the panic macro in a const context.

Re-exports§

Modules§

  • fmt
    Formatting-related items
  • utils
    Utility functions

Macros§

  • coerce_fmt
    Coerces $reff to a type that has a to_panicvals method, which is expected to return a [PanicVal<'_>; LEN].
  • concat_non_basic
    Concatenates PanicFmt constants into a &'static str
  • concat_assert
    Asserts that $condition is true.
  • concat_panic
    Panics with the concanenation of the arguments.
  • flatten_panicvalsnon_basic
    Formats multiple values into an array of PanicVals.
  • impl_panicfmtnon_basic
    Implements the PanicFmt trait and the to_panicvals method it requires.
  • inline_macronon_basic
    Helper macro for defining and using a macro_rules! macro inline.
  • unwrap_err
    Gets the value in the Err variant.
  • unwrap_ok
    Gets the value in the Ok variant.
  • unwrap_some
    Gets the value in the Some variant.

Structs§

  • ArrayString
    For precomputing a panic message.
  • PanicVal
    An opaque enum of the values that this crate knows how to format, along with some formatting metadata.
  • StdWrapper
    A wrapper type used to define methods for std types.

Constants§

  • MAX_PANIC_MSG_LEN
    The maximum length of panic messages (in bytes), after which the message is truncated.

Functions§

Derive Macros§